Crate shred

source ·
Expand description

Shared resource dispatcher

This library allows to dispatch systems, which can have interdependencies, shared and exclusive resource access, in parallel.

Examples

extern crate shred;

use shred::{DispatcherBuilder, Read, Resource, ResourceId, System, SystemData, World, Write};

#[derive(Debug, Default)]
struct ResA;

#[derive(Debug, Default)]
struct ResB;

#[derive(SystemData)] // Provided with `shred-derive` feature
struct Data<'a> {
    a: Read<'a, ResA>,
    b: Write<'a, ResB>,
}

struct EmptySystem;

impl<'a> System<'a> for EmptySystem {
    type SystemData = Data<'a>;

    fn run(&mut self, bundle: Data<'a>) {
        println!("{:?}", &*bundle.a);
        println!("{:?}", &*bundle.b);
    }
}

let mut world = World::empty();
let mut dispatcher = DispatcherBuilder::new()
    .with(EmptySystem, "empty", &[])
    .build();
world.insert(ResA);
world.insert(ResB);

dispatcher.dispatch(&mut world);

Once you are more familiar with how system data and parallelization works, you can take look at a more flexible and performant way to dispatch: ParSeq. Using it is bit trickier, but it allows dispatching without any virtual function calls.

Modules

Macros

  • par
    The par! macro may be used to easily create a structure which runs things in parallel.
  • seq
    The seq! macro may be used to easily create a structure which runs things sequentially.

Structs

  • AsyncDispatcher
    Like, Dispatcher but works asynchronously.
  • BatchAccessor
    The BatchAccessor is used to notify the main dispatcher of the read and write resources of the Systems contained in the batch (“sub systems”).
  • BatchUncheckedWorld
    The BatchUncheckedWorld wraps an instance of the world. You have to specify this as SystemData for a System implementing BatchController.
  • DefaultProvider
    A SetupHandler that simply uses the default implementation.
  • Dispatcher
    The dispatcher struct, allowing systems to be executed in parallel.
  • DispatcherBuilder
    Builder for the Dispatcher.
  • Entry
    An entry to a resource of the World struct. This is similar to the Entry API found in the standard library.
  • Fetch
    Allows to fetch a resource in a system immutably.
  • FetchMut
    Allows to fetch a resource in a system mutably.
  • MetaIter
    An iterator for the MetaTable.
  • MetaIterMut
    A mutable iterator for the MetaTable.
  • MetaTable
    The MetaTable which allows to store object-safe trait implementations for resources.
  • MultiDispatcher
    A bridge from MultiDispatchController to BatchController.
  • PanicHandler
    A setup handler that simply does nothing and thus will cause a panic on fetching.
  • Par
    Runs two tasks in parallel. These two tasks are called head and tail in the following documentation.
  • ParSeq
    A dispatcher intended to be used with Par and Seq structures.
  • Read
    Allows to fetch a resource in a system immutably.
  • ResourceId
    The id of a Resource, which simply wraps a type id and a “dynamic ID”. The “dynamic ID” is usually just left 0, and, unless such documentation says otherwise, other libraries will assume that it is always 0; non-zero IDs are only used for special resource types that are specifically defined in a more dynamic way, such that resource types can essentially be created at run time, without having different static types.
  • Seq
    Runs two tasks sequentially. These two tasks are called head and tail in the following documentation.
  • StaticAccessor
    The static accessor that is used for SystemData.
  • World
    A Resource container, which provides methods to insert, access and manage the contained resources.
  • Write
    Allows to fetch a resource in a system mutably.

Enums

Traits

  • Accessor
    A trait for accessing read/write multiple resources from a system. This can be used to create dynamic systems that don’t specify what they fetch at compile-time.
  • BatchController
    The BatchController describes things that allow one to control how batches of systems are executed.
  • CastFrom
    Helper trait for the MetaTable.
  • DynamicSystemData
    A struct implementing system data indicates that it bundles some resources which are required for the execution.
  • MultiDispatchController
    The controlling parts of simplified BatchControllers for running a batch fixed number of times.
  • Resource
    A resource is a data slot which lives in the World can only be accessed according to Rust’s typical borrowing model (one writer xor multiple readers).
  • RunNow
    Trait for fetching data and running systems. Automatically implemented for systems.
  • RunWithPool
    Similar to RunNow except additionally taking in a rayon::ThreadPool for parallelism.
  • SetupHandler
    A setup handler performing the fetching of T.
  • System
    A System, executed with a set of required Resources.
  • SystemData
    A static system data that can specify its dependencies at statically (at compile-time). Most system data is a SystemData, the DynamicSystemData type is only needed for very special setups.

Type Aliases

  • ReadExpect
    Allows to fetch a resource in a system immutably. This will panic if the resource does not exist. Usage of Read or Option<Read> is therefore recommended.
  • ResourcesDeprecated
    Alias for World for easier migration to the new version. Will be removed in the future.
  • WriteExpect
    Allows to fetch a resource in a system mutably. This will panic if the resource does not exist. Usage of Write or Option<Write> is therefore recommended.

Derive Macros

  • SystemData
    A reexport of the #[derive(SystemData] macro provided by shred-derive. This requires that the shred-derive feature is enabled. Used to #[derive] the trait SystemData.